/**
 * This file is part of the educational usermanagement system.
 * 
 * Copyright (c) 2008, Florian Arndt, Thomas Kemptner, Christian Kerl, Patrick Neuberger, Marcel Rehfeld, Emal Sadran, Stefan Sauer
 * 
 * Released under the MIT License http://www.opensource.org/licenses/mit-license.php
 */

package edu.ba.management.data;

import java.util.*;
import edu.ba.management.*;
import edu.ba.management.data.search.*;

/**
 * The IDataStore represents the minimal interface to access an user management
 * system compliant data store.
 */
public interface IDataStore
{
    /**
     * Saves a new or changed user in the data store. When its a new user the id
     * is set.
     * 
     * @param user the user to save
     * @return the saved user with valid id
     */
    public User store(User user);

    /**
     * Saves a new or changed group in the data store. When its a new group the
     * id is set.
     * 
     * @param group the group to save
     * @return the saved group with valid id
     */
    public Group store(Group group);

    /**
     * Removes an user from the data store and invalidates the id. The user is
     * also removed from all associated groups.
     * 
     * @param user the user to remove
     * @return the removed user with invalid id
     */
    public User remove(User user);

    /**
     * Removes a group from the data store and invalidates the id. The group is
     * also removed from all associated users.
     * 
     * @param group the group to remove
     * @return the removed group with invalid id
     */
    public Group remove(Group group);

    /**
     * Gets a cloned list of all users.
     * 
     * @return a list of all users
     */
    public List<User> getUsers();

    /**
     * Gets a cloned list of all groups.
     * 
     * @return a list of all groups
     */
    public List<Group> getGroups();

    /**
     * Gets a cloned user object by id.
     * 
     * @param id the id
     * @return the cloned user, or null if no user with the given id exists
     */
    public User getUserById(int id);

    /**
     * Gets a list of cloned user objects by ids.
     * 
     * @param ids the ids
     * @return the list of cloned users
     */
    public List<User> getUsersByIds(List<Integer> ids);

    /**
     * Gets a cloned group object by id.
     * 
     * @param id the id
     * @return the cloned group, or null if no group with the given id exists
     */
    public Group getGroupById(int id);

    /**
     * Gets a list of cloned group objects by ids.
     * 
     * @param ids the ids
     * @return the list of cloned groups
     */
    public List<Group> getGroupsByIds(List<Integer> ids);

    /**
     * Gets a cloned list of users, which match the criteria in the filter.
     * 
     * @param filter a FilterChain object, containing filter criteria
     * @return a filtered user list
     * 
     * @throws NoSuchFieldException if the filter contains a field that is not
     *             defined in the User class
     */
    public List<User> findUsers(FilterChain filter) throws NoSuchFieldException;

    /**
     * Gets a cloned list of groups, which match the criteria in the filter.
     * 
     * @param filter a FilterChain object, containing filter criteria
     * @return a filtered group list
     * 
     * @throws NoSuchFieldException if the filter contains a field that is not
     *             defined in the Group class
     */
    public List<Group> findGroups(FilterChain filter)
            throws NoSuchFieldException;
}
